Интеграция через backend

Используйте собственный backend или BFF, если покупка, заказ или подписка в Gigma открывает закрытые данные и функции вашего продукта.

Frontend отвечает за интерфейс. Gigma хранит клиента, заказ, оплату и подписку. Ваш backend связывает эти данные с локальным пользователем и принимает окончательное решение о доступе.

Когда backend обязателен

Backend нужен, если ваш продукт:

• хранит собственные закрытые данные;
• выдаёт платную функцию после покупки;
• должен скрыть Bearer клиента от браузера;
• обрабатывает webhooks;
• связывает одного клиента Gigma с локальным пользователем.

Публичный каталог, тарифы, страницы, блоки и меню можно получать напрямую из клиентского приложения по App Token. Личные методы Gigma доступны по Bearer клиента, но решение о доступе к вашим данным не должно приниматься на frontend.

Как разделена ответственность

Рекомендуемая схема:

Браузер
  │ HttpOnly cookie локальной сессии
  ▼
Backend / BFF продукта
  │ App Token + Bearer клиента
  ▼
Gigma API

Порядок интеграции

Шаг 1. Получите Bearer клиента

Проведите выбранный сценарий входа клиента через backend. После успешного входа Gigma вернёт Bearer.

Сохраните Bearer на сервере и свяжите его с локальным пользователем. Не отправляйте его обратно в браузер, если в этом нет технической необходимости.

Шаг 2. Создайте локальную сессию

После входа выдайте браузеру cookie вашей сессии. Используйте:

• HttpOnly, чтобы JavaScript не мог прочитать cookie;
• Secure, чтобы браузер передавал её только по HTTPS;
• SameSite, подходящий вашей доменной схеме;
• ограниченный срок действия и отзыв при выходе.

Bearer клиента не должен попадать в URL, browser storage, аналитику и обычные application-логи.

Шаг 3. Обращайтесь к Gigma от имени клиента

В запросах backend передавайте оба заголовка:

GET /api/counterparty/orders HTTP/1.1
Host: api.gigma.ru
Token: <application_token>
Authorization: Bearer <counterparty_token>
Accept: application/json

App Token выбирает Application, Bearer подтверждает клиента.

Шаг 4. Проверьте право доступа

Обычный заказ

1. Получите заказ через GET /api/counterparty/orders/{id}.
2. Убедитесь, что заказ относится к текущему клиенту и текущему Application. Gigma дополнительно проверяет эту связь.
3. Разрешайте действие только для заранее определённого оплаченного статуса.
4. Не доверяйте payment_link, query-параметрам страницы возврата и данным с frontend.

Подписка

Получите GET /api/counterparty/subscriptions, найдите нужный тариф и сначала проверьте, что оплаченный период ещё не закончился:

subscription.current_period_end > now

После этого примените одно правило продукта:

• закрывать доступ сразу после отключения автопродления — разрешайте только status == "active";
• сохранять доступ до конца оплаченного периода — разрешайте active, charging и canceled, пока current_period_end находится в будущем.

past_due не даёт доступ: оплаченный период уже закончился. Не определяйте право только по latest_payment.status.

Проверяйте состояние перед защищённым действием, а не только при входе пользователя. Полное описание статусов и вариантов правила находится в разделе «Подписки».

Шаг 5. Обрабатывайте изменения состояния

Webhook order.paid помогает быстро обновить локальное состояние, но не является единственным доказательством оплаты.

Обработчик webhook должен:

1. проверить X-Signature по исходному телу запроса и секрету webhook, привязанному к нужному Application;
2. сохранить event_id как ключ идемпотентности и не обрабатывать событие повторно;
3. повторно получить заказ или подписку из Gigma;
4. обновить локальное право только по актуальному ответу API.

Настройка webhooks описана в разделе «Платформа / Приложения».

Шаг 6. Завершайте обе сессии

При выходе пользователя:

1. вызовите POST /api/counterparty/logout;
2. удалите локальную сессию;
3. очистите серверное хранилище Bearer;
4. отзовите все устройства, если пользователь выбрал общий выход.

Готово: браузер работает только с локальной сессией, а backend проверяет актуальное состояние в Gigma перед выдачей доступа.

Introspect: когда он нужен

Introspect нужен, когда Bearer пришёл вашему backend из другой доверенной системы и его необходимо проверить отдельными client_id и client_secret.

В обычном BFF-сценарии backend сам получил Bearer от Gigma и может использовать его напрямую. Дополнительный introspect не требуется.

Heartbeat: что он подтверждает

Heartbeat обновляет время активности клиентской сессии. Он не подтверждает оплату, подписку или право на закрытую функцию.

Не используйте активную сессию как правило доступа.

Ошибки и повторы

Общие правила ответов и повторов находятся в соглашениях API.

Карта интеграции